Video Toaster 4.0/Video Toaster v4.0.iso/programs/documentation/modelerarexx.doc

Text File | 1994-06-28 | 21KB | 644 lines

MODELER AREXX INTERFACE
=======================
Updated 6/21/94


Modeler operates as a function host for function calls only.
"LWModelerARexx.port" is the function host address.


FUNCTION ARGUMENTS

Function arguments and return values are generally one of the fixed
set of types whose formats are listed below, although values may be
formatted in a specific way for some functions.  The standard formats
are shown here:

    number    -- a floating point or integer number.

            examples:    12  -99   0  1.23  -.5601  1.667e-3

    bool    -- a number where 0 is false and anything else is true
           (usually 1).

    vector    -- a triple of floating point numbers separated by spaces,
           or a single number.  A single number is interpreted as
           a vector with all three components the same.

            examples:    1 1 -1      .5 -12.6 0      0 -15 -13
            example:    2 and 2 2 2 give the same vector

    string    -- raw argument text

    keyword    -- one of several possible keywords, shown as <a|b|c...>
           Only enough of a keyword need be specified to
           distinguish it from the other possibilities.

            example:    axis <X|Y|Z>

    flags    -- a string that can contain any of a set of characters,
           shown as <a;b;c>.  If the character is present in the
           string, the flag it represents is set.  Likewise, if
           the character is not present the flag is clear.

            example:    ease <i;o>

    layers    -- a list of one or more layer numbers in the range 1-8.


INTERFACE MODES and STATES

The client ARexx interface has modes and states in which it operates.
Some commands are only valid in some modes, and some are valid in any
mode.  An attempt to use a command when the interface is in the wrong mode
will generate an error.

    NORMAL mode.  This is the default mode, and the one the interface
    starts in.  Most single-function commands are valid in this mode.

    ADD mode.  Started with ADD_BEGIN and exited with ADD_END.  Only
    the "add" data creation commands are allowed in this mode.

    TRANSFORM mode.  Started with XFRM_BEGIN and ended with XFRM_END.
    Only "xfrm" coordinate trasform commands are allowed in this mode.

    REPLICATE mode.  Started with REPL_BEGIN and ended with REPL_END.
    Only replication step commands are allowed in this mode.

Any of the above modes will also be terminated with a BEGIN command for
another of the modes, or the END_ALL command.

In addition to these mutually-exclusive modes, there is the REQUESTER
state, which is used to build and display a requester to the user for
input.  This additional mode is entered and exited with REQ_BEGIN and
REQ_END commands.  The "req" requester commands are only valid in
REQUESTER state, but other commands, including the mode change commands
above are valid regardless of REQUESTER state.

Certain selection functions are only valid in USER selection mode.  See
the section on selection below.


FUNCTION SUMMARY

Parameter types are shown in <>'s.  Trailing arguments which are
optional are shown in [], where any number of tailing arguments can
be omitted.

General:

    NEW()
         -- Clear all data.

    EXIT()
         -- Return to LightWave layout.  There can be no commands after
        this one.

    UNDO()
         -- Restore data from last change.

    DELETE()
         -- Delete contents of current layers.

    CUT()
         -- Cut current layers to paste buffer.

    COPY()
         -- Copy current layers to paste buffer.

    PASTE()
         -- Copy paste buffer to current layer.


File I/O:

    LOAD(filename<string>)
         -- Load data from LightWave file into current layer.

    SAVE(filename<string>)
         -- Store data from current layers into LightWave file.


State:

    SETLAYER(<layers>)
    SETBLAYER(<layers>)
         -- Switch active or background layers to show given list.

    SURFACE(name<string>)
         -- Set current surface to given name.  If it does not
        exist it will be created.

    END_ALL()
         -- Set mode to NORMAL regardless of current mode, and
        terminate REQUESTER state, if active.  This is done
        automatically when a script initiated from Modeler
        completes.


Point Transforms:

The "Flex" and "Deform" transformations use similar region data to define
the scope of their operations.  These are set globally and then applied
to all trasformations of a given type.

    FIXEDFLEX(axis<X|Y|Z>, start<number>, end<number>, [ease<i;o>])
         -- Set the flex functions to operate on a fixed range
        along an axis.  Ease flags are 'i' for ease-in and 'o'
        for ease-out.

    AUTOFLEX(axis<X|Y|Z>, direction<+|->, [ease<i;o>])
         -- Set the flex functions to operate on an automatic range
        along an axis of the given polarity.

    DEFORMREGION(radius<vector>, [center<vector>, axis<X|Y|Z>])
         -- Set the area of effect for the deformation tools.  If
        axis is omitted, the effect is bounded in all
        directions by the given radius.  If an axis is
        specified, the effect is unbounded along that axis.

    MOVE  (offset<vector>)
    SHEAR (offset<vector>)
    MAGNET(offset<vector>)
         -- Translate points by the given offset.  Shear translates
        along the flex axis.  Magnet translates in the deform
        region.

    ROTATE(angle<number>, axis<X|Y|Z>, [center<vector>])
    TWIST (angle<number>, axis<X|Y|Z>, [center<vector>])
    VORTEX(angle<number>, axis<X|Y|Z>, [center<vector>])
         -- Rotate points along the given axis by the angle given
        in degrees.  Twist uses the flex axis, and vortex uses
        the deform region.

    SCALE(factor<vector>, [center<vector>])
    TAPER(factor<vector>, [center<vector>])
    POLE (factor<vector>, [center<vector>])
         -- Scale points by the given factors around the given
        center.  Taper uses the flex axis, and pole uses the
        deform region.

    BEND(angle<number>, direction<number>, [center<vector>])
         -- Bend points by the given bend angle in the direction
        around the optional center.  This function uses the
        current flex axis.

    JITTER(radius<vector>)
         -- Randomly translate points within a given box.

(new)    JITTER(radius<vector>, [type<GAUSSIAN|UNIFORM|NORMAL|RADIAL>,
                center<vector>])
         -- Randomly translate points using different displacement
        functions.  UNIFORM is the default, which is the same
        as the old box jitter.  GAUSSIAN distributes the offsets
        in a bell curve around the start point.  NORMAL shifts
        the points in and out along the local surface normal.
        RADIAL shifts points in and out along a line through
        a central point given by center.

    SMOOTH([iterations<number>, strength<number>])
         -- Apply smoothing function to attempt to remove kinks in
        polygons connecting affected points.

    QUANTIZE(size<vector>)
         -- Snap all points to a 3D grid defined by the size vector.

    MERGEPOINTS([mindist<number>])
         -- Merge points lying within a certain minimum distance of
        each other.  If no distance is given, it is computed
        automatically.


Object Creation:

    MAKEBOX(lowcorner<vector>, highcorner<vector>, [nsegments<vector>])
         -- Make a box with the given extent and divisions.

    MAKEBALL(radius<vector>, nsides<int>, nsegments<int>, [center<vector>])
         -- Make a globe-style sphere.

    MAKETESBALL(radius<vector>, level<int>, [center<vector>])
         -- Make a tesselated sphere.

    MAKEDISC(radius<vector>, top<number>, bottom<number>, axis<X|Y|Z>,
         nsides<int>, [nsegments<int>, center<vector>])
         -- Make a disc.

    MAKECONE {same as disc}
         -- Make a cone.  Top is the pointy end.


Text:

    index<number> = FONTLOAD(filename<string>)
         -- Load the given font file into the font list.  Returns
        the font index in the table if loaded sucessfully, zero
        otherwise.

    count<number> = FONTCOUNT()
         -- Get number of fonts loaded.

    index<number> = FONTINDEX(name<string>)
         -- Get index for name.

    name<string> = FONTNAME(index<number>)
         -- Get name for index.

    width<number> = MAKETEXT(text<string>, index<number>,
                 [cornertype<SHARP|BUFFERED>, spacing<number>,
                  scale<number>, axis<X|Y|Z>, pos<vector>])
         -- Generate text using the given font index.  Returns width
        as computed from the font metrics.  Spacing is an additional
        distance to put between characters (normally 0).  Scale is
        a scale factor (or approximate size in meters).  Axis and
        pos define the position of the first character and the plane
        in which the text will lie.


Query Functions:

    active<layers> = CURLAYER()
         -- Returns current active layer numbers.

    background<layers> = CURBLAYER()
         -- Returns current background layer numbers.

    empty<layers> = EMPTYLAYERS()
         -- Returns numbers of empty layers.

    name<string> = CURSURFACE()
         -- Returns current surface name.

    boxdata = BOUNDINGBOX([test<layers>])
         -- Returns bounding box information for the given layers or the
        current layers if none given.  Bounding box is a string:

            num x0 x1 y0 y1 z0 z1

        num is number of points tested.  If 0, the remaining values
        are also zero.  The remaining values are the low and high
        in the three axes -- 0 is low, 1 is high.


Additional:

    LATHE(axis<X|Y|Z>, nsides<int>,
          [center<vector>, endangle<number>, startangle<number>])
         --    Spin template around axis.

    EXTRUDE(axis<X|Y|Z>, extent<number>, [nsegments<int>])
         --    Sweep template along axis.

    MIRROR(axis<X|Y|Z>, plane<number>)
         -- Copy selected data, fliping it through a plane.

    PATHCLONE(...)
    PATHEXTRUDE(filename<string>, [step<number>,
            start<number>, end<number>])
         -- Load the motion file and extrude or clone selected data
        according to path interval settings.

    RAILCLONE(...)
    RAILEXTRUDE(segments<number>, [divs<KNOTS|LENGTHS>, flags<o;s>,
            strength<number>])
         -- Clone or extrude selected data using rails in background
        layers.  If segments is zero, they are computed automatically,
        otherwise it is a fixed division.  Flags are 'o' for
        oriented and 's' for scaled.

    AXISDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, axis<X|Y|Z>,
          [surface<string>])
         -- Use background layers as template to operate on foreground
        layers.  Surface is used for STENCIL operation.

    SOLIDDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, [surface<string>])
         -- Use background object to operate on foreground.

    BOOLEAN(operation<UNION|SUBTRACT|INTERSECT|ADD>)
         -- Combine background object with foreground data.

    BEVEL(inset<number>, shift<number>)
         -- Perform bevel operation on selected polygons.

    SHAPEBEVEL(pattern)
         --    Bevel with a shape defined by a series of insets and
        shifts.  The pattern is a blank-separated list of
        inset/shift pairs, each relative to the original polygon.
        The same effect can be achieved using iterative bevels,
        but the results are not always correct because of self-
        crossing.

    SMOOTHSHIFT(offset<number>, [maxangle<number>])
         -- Shift selected polygons by given offset.  Any angles
        greater than maxangle will cause the surface to break.

    FLIP()
         -- Flip sidedness of faces, direction of curves.

    TRIPLE()
         -- Convert all polygons into triangles.

    REMOVEPOLS()
         -- Remove polygons leaving points.

    ALIGNPOLS()
         -- Flip polygons so all are facing the same direction (as
        much as is possible).

    UNIFYPOLS()
         -- Delete any duplicate polygons.

    CHANGESURFACE(surface<string>)
         -- Set the surface of all selected polygons.

    SUBDIVIDE(mode<FLAT|SMOOTH|METAFORM>, [maxangle<number>])
         -- Split all triangles into four smaller triangles.
(new)        Also splits quads into four smaller quads.  Metaform
        option uses the metaform algorithm.

(new)    FRACSUBDIVIDE(mode<FLAT|SMOOTH|METAFORM>, fractal<number>,
              [maxangle<number>])
         -- Same as subdivide, but applies a fractal displacement
        to each new vertex as a function of its position.

    FREEZECURVES()
         -- Convert all selected curves directly into polygons.


Data Creation (ADD mode):

    ADD_BEGIN()
         -- Enter data creation (ADD) mode.  Points and polygons
        can be added.  Other operations are illegal except
        for the SURFACE command which sets surface for new
        polygons.

    index<int> = ADD_POINT(position<vector>)
         -- Points are numbered in creation order starting at 1.
        The index of the new point is returned.

    ADD_POLYGON(<point number list>)
         -- Takes a variable number of point numbers as argument.
        Polygon is created using current default surface.

    ADD_QUAD(<point number list>)
         -- Takes a variable number of point numbers, up to four.
        Polygon is created using current default surface and
        will have 2 sides or be made with triangles if those
        flags are set.

    ADD_CURVE(<point number list>, [ccstate])
         -- Takes a variable number of point numbers as argument.
        Curve is assigned current default surface.  Ccstate
        gives the condition of the continuity control points
        at the start and end.  If the ccstate argument
        contains 's', the first point in the list is a CC
        point.  If the string contains 'e', the same for the
        last point in list.

    ADD_END()
         -- Exit data creation mode.  New data will appear in the
        layer at this time and the whole operation can be
        undone as an atomic command.


Point Transform (TRANSFORM mode):

    n<number> = XFRM_BEGIN()
         -- Start a point transformation.  Returns number of points in
        the current layer.  If the number returned is zero, there
        are no points to process and TRANSFORM mode is not entered.

    pos<vector> = XFRM_GETPOS(index<number>)
         -- Get position of indexed point.  Index is from 1 to N.

    XFRM_SETPOS(index<number>, position<vector>)
         -- Move the indexed point to a new position.

    XFRM_END()
         -- Complete the transform and move all the points to their
        new positions.  END_ALL aborts the transform.


Sweep and Copy (REPLICATE mode):

    REPL_BEGIN(mode<COPY|SWEEP>)
         -- Start replication.  This is a copy or sweep, given by
        the argument.

    REPL_STEP(offset<vector>, scale<vector>, rotation<vector>,
          [center<vector>])
         -- Set the next step of the replication.  Offset is a shift.
        Rotation is a vector of (H,P,B) which is rotation around
        the Y, X and Z axes, respectively.  Rotation and scaling
        will occur around optional center.  To get a first step
        that is the same as the start pattern, REPL_STEP(0,1,0)
        must be included in the sequence.

    REPL_END()
         -- Complete the replication creating new data.  END_ALL can be
        used to abort the operation.


Selection:

Selection can be in two modes.  In the GLOBAL mode, all points and polygons
in active layers are selected for operation.  This is the default selection
mode.  In USER mode, the selection set in the main window is honored by
rexx functions.  This selection can also be altered.

    SEL_MODE(newmode<GLOBAL|USER>)
         --    Set the selection mode.  END_ALL or script termination
        will reset this mode to GLOBAL.

    SEL_POINT(action<SET|CLEAR>, [condition ...])
         --    Modify point selection.  Only valid in USER mode, and
        the user's selection mode will be changed to point if
        it is not already.  If there is no condition, the
        action will apply to all points.  Otherwise, the points
        specified by the condition will be added to the
        selection for SET and removed from the selection for
        CLEAR.  The possible conditions with their additional
        arguements are:

        VOLUME, lo<vector>, hi<vector>
             -- points within the volume.

        CONNECT
             -- points connected to already selected ones.  Only
            works with SET.

        NPEQ, npol<number>
             --    points belonging to exactly npol polygons.

        NPLT, npol<number>
             --    points belonging to less than npol polygons.

        NPGT, npol<number>
             --    points belonging to more than npol polygons.

    SEL_POLYGON(action<SET|CLEAR>, [condition ...])
         --    Modify polygon selection.  Like SEL_POINT, with the
        following conditions:

        VOLEXCL, lo<vector>, hi<vector>
             -- polygons entirely within the volume.

        VOLINCL, lo<vector>, hi<vector>
             -- polygons at least partly within the volume.

        CONNECT
             -- polygons connected to already selected ones.  Only
            works with SET.

        NVEQ, nvert<number>
             --    polygons with exactly nvert vertices.

        NVLT, nvert<number>
             --    polygons with less than nvert vertices.

        NVGT, nvert<number>
             --    polygons with greater than nvert vertices.

        SURFACE, surface<string>
             -- polygons having the given surface.

        FACE
             -- face polygons only.

        CURVE
             -- curve polygons only.

        NONPLANAR, [limit<number>]
             -- polygons less planar than the given limit.  If
            limit is omitted, it is the user's default limit.

(new)    SEL_INVERT()
         -- Invert selection.  Selected becomes unselected and visa
        versa.

(new)    SEL_HIDE(state<SELECTED|UNSELECTED>)
         -- Hide all selected or unselected data.  Default is SELECTED.

(new)    SEL_UNHIDE()
         -- Unhide all hiden data.


User Interface:

    ok<bool> = NOTIFY(type<number>, line1<string>, [line2, ...])
         -- Puts up a simple notification requester and returns user
        choice if one given.  Type is 1 for simple OK only
        notification and the function always returns 1.  Type 2
        is OK/Cancel request and function returns 1 for OK, 0
        for Cancel.  Type 3 is Yes/No request and the function
        returns 1 for Yes.  The remaining arguments are text
        lines, which will be in the default color unless preceded
        by '@' or '!' for increasingly strong emphasis colors.

    fnam<string> = GETFILENAME(title<string>, dir<string>, [nam<string>])
         -- Get a filename from the user.  Title is the title text
        for the file requester.  Dir is the start directory and
        nam is the optional name to start with in that directory.
        The return value is a name plus a path which clients will
        have to parse themselves if they want parts of the name.
        The string "(none)" is returned if the user cancels.

A client ARexx macro can put up a requester to get input from the user.
The interface is a set of functions to set up the request and get the
user's responses.

    REQ_BEGIN(header<string>)
         -- Start a requester box interaction.  The requester box will
        have the given header string at the top.

    id = REQ_ADDCONTROL(label<string>, type<string>, [opts, ...])
         -- Add a user input control with the given label text and
        description.  The type is a code for the type of control
        to create, and subsequent arguments are provided
        depending on type.

        type           code   other args
        ----           ----   ----------
        string        S     width (number of characters)
        number        N     units (flag for meters(1) or unitless(0))
        vector        V     units
        v-choice    CV    text1 text2 text3 ...
        h-choice    CH    ...
        boolean        B
        text-line    T     line1, line2, ...
        surface        R
        font        F

        Controls must be all added before any attempt to set or
        get values, or to post.

    REQ_SETVAL(id, value ...)
         -- Set the value of the control.  Interpretation of value
        argument(s) depends on control type.  Text-line controls
        have no value.

        type      value args
        ----      ----------
        string      text<string>
        number      value<number>, [default<number>]
        vector      value<vector>, [default<number>]
        choice      index<number 1..N>
        boolean      state<bool>
        surface      name<string>
        font      index<number 1..fontcount()>

    ok<bool> = REQ_POST()
         -- Posts request box and returns 1 for Ok, 0 for Cancel.

    value = REQ_GETVAL(id)
         -- Get the value of the control.  Interpretation of the
        value string depends on the type of the control.  Values
        are as they are in SETVAL, with vectors always returned
        as a triple.

    REQ_END()
         -- Complete requester interaction.  Each request must be
        complete before the next begins.

A client ARexx macro can configure the custom ARexx commands available
to the interactive user.

    ok<bool> = RXCMD_ADD(name<string>, cmd<string>)
         -- Add the given command string to the interface with the
        given descriptive name.  Returns true if item could
        be added.

    RXCMD_REMOVE(name<string>)
         -- Remove the command from interface given its descriptive
        name.

    cmd<string> = RXFUN_GET(n<number>)
         -- Get the command string for function key n (1..10).

    RXFUN_SET(n<number>, cmd<string>)
         -- Set the command string for function key n (1..10).  Since
        any change made here will be saved in the config file,
        scripts that do this should probably restore the old
        command before exiting.


A macro can show how it is progressing through the stages of an operation
with the progress meter.  Metering is a state that can co-exist with any
mode or with a requester.

    METER_BEGIN(count<int>, header<string>, [footer<string>])
         -- Initiate progress meter with the given main header and
        optional footer.  The count is the number of times
        METER_STEP() will be called before operation is done.

    METER_STEP()
         -- Step the progress meter one step closer to completion.
        Will return an error if the initial count is exceeded,
        or if the user requests an abort.

    METER_END()
         -- Deactivate meter.  Can be called before process final
        count is reached.